Web IDL support 2/N: response JSON serialization #155

AlfioEmanueleFresta · 2025-12-19T00:07:09Z

⚠️ AI-Assisted PR: This pull request was developed with the assistance of an AI coding agent (Claude Opus 4.5).

Summary

This PR is the second in a series (follows #138) and adds JSON serialization for WebAuthn responses - the inverse of the existing JSON request parsing functionality.

Changes

New Response Serialization Infrastructure

Add WebAuthnIDLResponse trait - Provides to_json() and to_inner_model() methods for converting responses to JSON format
Add JsonFormat enum - Supports both minified and prettified JSON output
Add ResponseSerializationError - Error type for serialization failures

New JSON Response Models (per WebAuthn Level 3 spec)

RegistrationResponseJSON - For MakeCredentialResponse serialization
AuthenticationResponseJSON - For Assertion serialization
AuthenticatorAttestationResponseJSON - Attestation response details
AuthenticatorAssertionResponseJSON - Assertion response details
AuthenticationExtensionsClientOutputsJSON - Extension output serialization

Request Structure Refactoring

Refactored MakeCredentialRequest and GetAssertionRequest to enable client data generation on-the-fly:

Replaced hash: Vec<u8> with challenge: Vec<u8> - Store raw challenge instead of pre-computed hash
Added origin: String field - Store origin explicitly
Added cross_origin: Option<bool> field - Optional cross-origin flag
Removed client_data: ClientData field - No longer needed as separate field
Added helper methods:
- client_data() - Builds ClientData internally
- client_data_hash() - Computes SHA-256 hash on demand
- client_data_json() - Returns JSON bytes for response serialization

Implementation Details

Implemented WebAuthnIDLResponse for MakeCredentialResponse with full attestation object CBOR serialization
Implemented WebAuthnIDLResponse for Assertion with signature and authenticator data handling
Support for extension outputs: credProps, hmacCreateSecret, hmacGetSecret, largeBlob, prf
Added Serialize derives to attestation statement types for CBOR encoding

Updated Files

All example files updated to use new request structure
All test files updated
CTAP2 model conversions updated to use client_data_hash()
U2F fallback code updated
WebAuthn preflight logic updated

Testing

All 85 existing tests pass
New unit tests added for response serialization
Updated webauthn_json_hid.rs example to demonstrate JSON response output

Example Usage

use libwebauthn::ops::webauthn::{WebAuthnIDLResponse, JsonFormat};

// After a MakeCredential operation
let response = channel.webauthn_make_credential(&request).await?;
let json = response.to_json(&request, JsonFormat::Prettified)?;
println!("{}", json);

// After a GetAssertion operation  
for assertion in &response.assertions {
    let json = assertion.to_json(&request, JsonFormat::Minified)?;
    println!("{}", json);
}

AlfioEmanueleFresta · 2025-12-19T00:25:36Z

@msirringhaus — Following up on your review comment on PR #138 regarding clientExtensionResults handling:

I investigated the WebAuthn Level 3 specification and found that clientExtensionResults is marked as required in both response types:

RegistrationResponseJSON: required AuthenticationExtensionsClientOutputsJSON clientExtensionResults;
AuthenticationResponseJSON: required AuthenticationExtensionsClientOutputsJSON clientExtensionResults;

This matches the behavior observed on demo.yubico.com, which always returns "clientExtensionResults": {} even when no extensions produce output.

So the current implementation in this PR is correct — we always include clientExtensionResults (as an empty object {} if no extensions produced output). The two cases you mentioned:

Extensions absent in request → Response includes "clientExtensionResults": {}
Extensions present but empty (extensions: {}) → Response includes "clientExtensionResults": {}

Both cases result in the same output per the spec, since clientExtensionResults is always required.

This comment was written by GitHub Copilot (Claude) operating on @AlfioEmanueleFresta's instructions.

This adds the inverse of JSON request parsing - serializing WebAuthn responses back to JSON format per WebAuthn Level 3 specification. Changes: - Add WebAuthnIDLResponse trait for response-to-JSON conversion - Add RegistrationResponseJSON and AuthenticationResponseJSON models - Implement to_json() for MakeCredentialResponse and Assertion - Refactor requests to store challenge/origin/cross_origin separately - Add client_data_hash() and client_data_json() helper methods - Update all examples and tests to use new request structure - Add unit tests for response serialization

msirringhaus

Looking good to me. Some minor comments and questions inline.

msirringhaus · 2026-01-08T12:26:19Z

libwebauthn/src/ops/webauthn/client_data.rs

 impl ClientData {
-    pub fn hash(&self) -> Vec<u8> {
+    /// Returns the canonical JSON representation of the client data.
+    pub fn to_json_bytes(&self) -> Vec<u8> {


I wonder if it would be more versatile to make this to_json() and return a String. Those who need the bytes can then call into_bytes() on the result.

msirringhaus · 2026-01-08T12:27:03Z

libwebauthn/examples/webauthn_prf_hid.rs

-        hash: Vec::from(challenge),
+        challenge: Vec::from(challenge),
+        origin: "example.org".to_string(),
+        cross_origin: None,


Do we have any tests where cross_origin is not None?

msirringhaus · 2026-01-08T12:28:25Z

libwebauthn/src/ops/webauthn/get_assertion.rs

+        self.client_data().hash()
+    }
+
+    pub fn client_data_json(&self) -> Vec<u8> {


Same question as above. More so here: The naming client_data_json() would lead me to expect a String.

libwebauthn/src/ops/webauthn/get_assertion.rs

msirringhaus · 2026-01-08T12:36:09Z

libwebauthn/src/ops/webauthn/get_assertion.rs

+        let parsed: serde_json::Value = serde_json::from_str(&json_str).unwrap();
+
+        // Verify required fields
+        assert!(parsed.get("id").is_some());


Do we want to also check the contents of the fields, not just if they are Some()?

msirringhaus · 2026-01-08T12:46:07Z

libwebauthn/src/ops/webauthn/idl/response.rs

+
+/// JSON output format options.
+#[derive(Debug, Clone, Copy, Default)]
+pub enum JsonFormat {


Is it intentional to 'reimplement' this, instead of exposing a serde_json-Value, which the user can then use and format according to whatever serde_json offers?
I don't have a strong preference for either way, just wanting to understand the reasoning better, if there is any.

msirringhaus · 2026-01-08T12:57:32Z

libwebauthn/src/ops/webauthn/make_credential.rs

+        request: &Self::Context,
+    ) -> Result<Self::InnerModel, ResponseSerializationError> {
+        // Get credential ID from attested credential data
+        let credential_id_bytes = self


Same comment as for the GetAssertion-case regarding crential IDs.

msirringhaus · 2026-01-08T12:59:49Z

libwebauthn/src/ops/webauthn/make_credential.rs

+            },
+            authenticator_attachment: None,
+            client_extension_results,
+            r#type: "public-key".to_string(),


I'm ok with this for now, as we do it in lots of places, but somehow my engineering mind would feel more at ease, if we could make this a transparent enum instead of a hardcoded string in a bunch of places, to avoid typos. But this doesn't have to be in this PR.

msirringhaus · 2026-01-08T13:25:37Z

libwebauthn/src/ops/webauthn/make_credential.rs

+        let parsed: serde_json::Value = serde_json::from_str(&json_str).unwrap();
+
+        // Verify required fields
+        assert!(parsed.get("id").is_some());


Same as with GetAssertion: Can we check the contents as well for those that are easy/obvious?

AlfioEmanueleFresta changed the title ~~feat(idl): Add WebAuthn response JSON serialization~~ Web IDL support 2/N: response JSON serialization Dec 19, 2025

AlfioEmanueleFresta changed the base branch from master to json December 19, 2025 00:08

AlfioEmanueleFresta force-pushed the json-2 branch from 41fbcff to 68c78a6 Compare December 19, 2025 00:15

AlfioEmanueleFresta force-pushed the json-2 branch from 68c78a6 to d3c31bb Compare December 19, 2025 00:28

AlfioEmanueleFresta marked this pull request as ready for review December 25, 2025 15:51

AlfioEmanueleFresta force-pushed the json branch from fbb40b2 to 39cca52 Compare December 26, 2025 20:31

AlfioEmanueleFresta added 5 commits December 26, 2025 20:41

[WIP] More progress

885b452

Make Credential parsing seems working; added example

06ee7c0

Change back CTAP2 credential model to ByteBuf

0ac3bb7

Rebased

d97c80d

AlfioEmanueleFresta force-pushed the json-2 branch from d3c31bb to d97c80d Compare December 26, 2025 20:56

AlfioEmanueleFresta mentioned this pull request Dec 26, 2025

Use libwebauthn for JSON request parsing linux-credentials/credentialsd#116

Open

AlfioEmanueleFresta requested a review from msirringhaus December 27, 2025 00:00

msirringhaus requested changes Jan 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Web IDL support 2/N: response JSON serialization #155

Web IDL support 2/N: response JSON serialization #155

Uh oh!

AlfioEmanueleFresta commented Dec 19, 2025

Uh oh!

AlfioEmanueleFresta commented Dec 19, 2025

Uh oh!

msirringhaus left a comment

Uh oh!

msirringhaus Jan 8, 2026

Uh oh!

msirringhaus Jan 8, 2026

Uh oh!

msirringhaus Jan 8, 2026

Uh oh!

Uh oh!

msirringhaus Jan 8, 2026

Uh oh!

msirringhaus Jan 8, 2026

Uh oh!

msirringhaus Jan 8, 2026

Uh oh!

msirringhaus Jan 8, 2026

Uh oh!

msirringhaus Jan 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Web IDL support 2/N: response JSON serialization #155

Are you sure you want to change the base?

Web IDL support 2/N: response JSON serialization #155

Uh oh!

Conversation

AlfioEmanueleFresta commented Dec 19, 2025

Summary

Changes

New Response Serialization Infrastructure

New JSON Response Models (per WebAuthn Level 3 spec)

Request Structure Refactoring

Implementation Details

Updated Files

Testing

Example Usage

Uh oh!

AlfioEmanueleFresta commented Dec 19, 2025

Uh oh!

msirringhaus left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants